The present invention is related to computer software and more specifically to automated training computer software.
To train engineers on the operation of complex computer software, it can be helpful to perform a xe2x80x9ccode walk-through.xe2x80x9d In a code walk-through, engineers being trained are shown a portion of the computer software source code known as the code, as an instructor describes how that portion of the code operates. The description may contain an explanation of a complexity or nuance that an engineer might not notice by himself.
The problem with a code walk-through is that it is very labor-intensive. A trained instructor must perform it with one or more engineer-trainees. The instructor and the engineers are required to be present at the same time to perform the walk-through. Because of the expense of the instructor, code walk-throughs may be scheduled only when a sufficient number of engineers require training. The first engineers to require training must wait until others require it as well; leaving the first engineers untrained for some period of time. If the instructor leaves the company, he must train another trainer, which is not only labor intensive, but can also cause details to become lost if they are not communicated from one trainer to the next.
These problems have been addressed with text-based code walk-throughs. A text-based code walk-through contains the code and explanatory material in text-based form. For example, one side of a page may contain the software code and the other side contains a text based description of the code, similar to that which an instructor would relate in a classroom. Arrows from the description to the relevant code section may be placed on the page to allow the reader to identify the pertinent code section described. Instead of arrows, a footnote arrangement may also be used.
However, as the computer software being described changes, the description must move with the pertinent section of the code it describes to allow the engineer trainees to easily locate the code being described. For a large computer program that may change frequently, the maintenance of the description becomes a monumental task. This task is made even more difficult when minor changes are made to the code described by the description, making it difficult to locate the pertinent code section described.
What is needed is a method and apparatus that can allow a text based code walk-though description to automatically change location with the pertinent code, even if minor changes are made to the text of the code itself.
A method and apparatus reads two files, a source file, containing an item such as source code, and an annotation file, containing descriptions of different portions of the item. The annotation file also contains commands to the method and apparatus, beginning with codes known as xe2x80x9ctagsxe2x80x9d. The method and apparatus writes two output files, an annotation HTML file and a source HTML file, that are similar to the corresponding input files, except they do not contain the commands, and contain cross links to the other output file, allowing the relationship between the annotation HTML file and the source HTML file to be automatically generated. The tags describe where to locate the cross links. A xe2x80x9cmatch tagxe2x80x9d instructs the method and apparatus to build a cross link between the current location of the annotation HTML file and a specific location in the source HTML file. The specific location is identified by the method and apparatus by locating text in the source input file that is similar to the text contained in the command beginning with the match tag. A command beginning with a xe2x80x9cset confidence level tagxe2x80x9d determines the degree of similarity required to identify the specific location in the source HTML file. Other commands starting with other tags allow HTML commands or spaces to be inserted into the annotation HTML file. The method and apparatus can build other links to the other output file as well as links within the same output file.